# Browserslist

Rsbuild supports using [Browserslist](https://browsersl.ist/) to specify which browsers should be supported in your Web application.

## What is Browserslist

Since different browsers support ECMAScript and CSS differently, developers need to set the correct browser range for web applications.

[Browserslist](https://browsersl.ist/) can specify which browsers your web application can run in, it provides a configuration for specifying browsers range. Browserslist has become a standard in the industry, it is used by libraries such as SWC, Lightning CSS, Babel, ESLint, PostCSS and webpack.

When you specify a browser range through Browserslist, Rsbuild will compile JavaScript and CSS code to the specified syntax.

## Polyfill Injection

If you enabled [output.polyfill](/config/output/polyfill), Rsbuild will also inject the corresponding polyfill code based on browserslist. **When you only need to support more modern browsers, the build process will introduce less compatibility code and polyfills, and the performance of the page will be better.**

```js
export default {
  output: {
    polyfill: 'usage',
  },
};
```

For example, when you need to be compatible with IE11 browser, Rsbuild will compile the code to ES5 and inject the polyfill required by IE11 through `core-js`.

> Please refer to [Browser Compatibility](/guide/advanced/browser-compatibility) for more information.

## Set Browserslist

You can set the Browserslist value in the `package.json` or `.browserslistrc` file in the root directory of the current project.

### Example

Set via `browserslist` in `package.json`:

```json title="package.json"
{
  "browserslist": [
    "iOS >= 9",
    "Android >= 4.4",
    "last 2 versions",
    "> 0.2%",
    "not dead"
  ]
}
```

Set via a separate `.browserslistrc` file:

```yaml title=".browserslistrc"
iOS >= 9
Android >= 4.4
last 2 versions
> 0.2%
not dead
```

### Effective Scope

By default, the `.browserslistrc` file only takes effect for browser-side bundles, including the `web` and `web-worker` target types.

When you are building multiple targets at the same time, for example if the targets contains both `web` and `node`, only the `web` bundles will be affected by the `.browserslistrc` file. If you want to make changes to the `node` bundles, you can use the `output.overrideBrowserslist` configuration below.

### Set by Env

You can set different browserslist based on `NODE_ENV` to specify different browser ranges for development and production.

For example, set values based on keys in the `package.json`:

```json title="package.json"
{
  "browserslist": {
    "production": [
      "chrome >= 87",
      "edge >= 88",
      "firefox >= 78",
      "safari >= 14"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}
```

Or in `.browserslistrc`:

```yaml title=".browserslistrc"
[production]
chrome >= 87
edge >= 88
firefox >= 78
safari >= 14

[development]
last 1 chrome version
last 1 firefox version
last 1 safari version
```

### overrideBrowserslist

In addition to the above standard usage, Rsbuild also provides [output.overrideBrowserslist](/config/output/override-browserslist) config, which can also set the value of Browserslist.

`overrideBrowserslist` can be set to an array, which is written in the same way as the `browserslistrc` configuration, but has a higher priority than `browserslistrc`.

```ts title="rsbuild.config.ts"
export default {
  output: {
    overrideBrowserslist: [
      'iOS >= 9',
      'Android >= 4.4',
      'last 2 versions',
      '> 0.2%',
      'not dead',
    ],
  },
};
```

In most cases, it is recommended to use the `.browserslistrc` file rather than the `overrideBrowserslist` config. Because the `.browserslistrc` file is the official config file, it is more general and can be recognized by other libraries in the community.

## Commonly used Browserslist

The following are some commonly used Browserslist, you can choose according to your project type.

### Desktop PC scenario

In the desktop PC scenario, if you need to be compatible with IE 11 browsers, you can set Browserslist to:

```yaml title=".browserslistrc"
> 0.5%
not dead
Internet Explorer 11
```

The above Browserslist will compile the code to the ES5 specification. For the specific browser list, please check [browserslist.dev](https://browserslist.dev/?q=PiAwLjUlLCBub3QgZGVhZCwgSUUgMTE%3D).

If you don't need to be compatible with IE 11 browsers, you can adjust Browserslist to get a more performant output, such as:

- Set to browsers that supports native ES Modules (recommended):

```yaml title=".browserslistrc"
chrome >= 87
edge >= 88
firefox >= 78
safari >= 14
```

- Set to browsers that support ES6:

```yaml title=".browserslistrc"
chrome >= 51
edge >= 15
firefox >= 54
safari >= 10
ios_saf >= 10
```

### Mobile H5 scenario

The mobile H5 scenario is mainly compatible with `iOS` and `Android` systems, usually we set Browserslist as:

```yaml title=".browserslistrc"
iOS >= 9
Android >= 4.4
last 2 versions
> 0.2%
not dead
```

The above Browserslist will compile the code to the ES5 specification, which is compatible with most mobile scenarios on the market. For the detailed browsers list, please check [browserslist.dev](https://browserslist.dev/?q=aU9TID49IDksIEFuZHJvaWQgPj0gNC40LCBsYXN0IDIgdmVyc2lvbnMsID4gMC4yJSwgbm90IGRlYWQ%3D).

![](https://assets.rspack.dev/rsbuild/assets/browserslist-dev-example.png)

You can also choose to use the ES6 specification in the H5 scene, which will make the performance of the page better. The corresponding Browserslist is as follows:

```yaml title=".browserslistrc"
iOS >= 10
Chrome >= 51
> 0.5%
not dead
not op_mini all
```

## Default Browserslist

Rsbuild will set different default values of Browserslist according to [output.target](/config/output/target), but we recommend that you explicitly set Browserslist in your project, which will make the compatible scope of the project more clear.

### Web Target

The default values of web target are as follows:

```yaml title=".browserslistrc"
chrome >= 87
edge >= 88
firefox >= 78
safari >= 14
```

Under this browser range, JavaScript code will be compatible with browsers that support [native ES Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules).

### Node Target

Node target will be compatible with Node.js 16.0 by default.

```yaml title=".browserslistrc"
node >= 16
```

### Web Worker Target

The default Browserslist of the web worker target is consistent with the web target.

```yaml title=".browserslistrc"
chrome >= 87
edge >= 88
firefox >= 78
safari >= 14
```

### Service Worker Target

The default Browserslist of the service worker target is consistent with the web target.

```yaml title=".browserslistrc"
chrome >= 87
edge >= 88
firefox >= 78
safari >= 14
```

## Query browser support

When developing, we need to know the browser support of certain features or APIs. At this time, we can check on the [caniuse](https://caniuse.com/) website.

For example, we need to know the browser support of `Promise`, just enter `Promise` in [caniuse](https://caniuse.com/), and you can see the following results:

![](https://assets.rspack.dev/rsbuild/assets/caniuse-promise-example.png)

As can be seen from the above table, `Promise` is natively supported in Chrome 33 and iOS 8, but not in IE 11.
